Memory

Refer to appendix II, “C Code Usage,” for a discussion of Prograph data types and of the type macintosh.  Types ABlock, ABlock@, and ABlock@@ are Mac types corresponding to a buffer, pointer to a buffer, and handle to a buffer, respectively. Many of the primitives in this category accept inputs that are direct, indirect (pointer), and doubly indirect (handle) references, and in fact also convert integers to pointers where appropriate. The Gets (such as get-integer) and Puts (such as put-real) output an incremental offset (original offset + size of data), to ensure proper positioning for the next Get or Put. In general, these primitives provide ways to manipulate heterogeneous data (obtained by reading from a file, for example) in memory buffers.

_________________________________________________
 
                                      address-to-object
 *313*

Input types: integer; [ boolean ]

Output types: any

Description: Object is the Prograph Object at the specified Address. Address must have been generated by a call to object-to-address on the same machine (same address space), and you must be certain that the object still exists at that address.  Release? is FALSE by default. If Release?, then Address is not valid.

See also: 
object-to-address

_________________________________________________
 
                                           block-address
*313*

Input types: ABlock

Output types: integer

Description: 
Address is the address of the first character in Block. Block should be locked whenever Address is taken or used.

See also:  string-address

_________________________________________________
                                           block-size
 *314*

Input types: macintosh

Output types: integer

Description: 
Size is the value of the size field of Mac.

See also:  new-block

_________________________________________________
                                           compact-memory
 *314*

Description:
Compacts memory. Use this primitive if you are using Macintosh methods which require a lot of memory.

_________________________________________________
                                      from-handle
*314*

Input types: macintosh

Output types: integer

Description: 
Mac must be a handle to a Macintosh structure, and Address is the address of the handle’s master pointer.

See also:  to-handle, to-pointer, from-pointer

_________________________________________________
                                       from-pointer
*314*

Input types: macintosh

Output types: integer

Description: 
Mac must be a pointer to a Macintosh structure, and Address is the address of that structure.

See also:  to-pointer, to-handle, from-handle

_________________________________________________
                                                get-integer 
 *315*

Input types: ABlock[@[@]] | integer;  integer;  integer

Output types: ABlock[@[@]] | integer;  integer;  integer

Description: 
Value is an integer of length Size bytes, read from Buffer starting at Offset bytes. Size must be 1, 2, or 4. NextOffset is Offset + Size.

See also:  put-integer, get-point, get-real, get-rect, get-string, get-text, sign-extend

_________________________________________________
                                                    get-point 
 *315*

Input types: ABlock[@[@]] | integer;  integer

Output types: ABlock[@[@]] | integer;  integer;  Point

Description: 
aPoint is a point obtained by reading four bytes from Buffer starting at Offset bytes. NextOffset is Offset + 4.

See also:  put-point, get-integer, get-real, get-rect, get-string, get-text

_________________________________________________
                                                   get-real 
 *315*

Input types: ABlock[@[@]] | integer;  integer

Output types: ABlock[@[@]] | integer;  integer;  real

Description: 
Value is a real of length Size bytes, read from Buffer starting at Offset bytes. Size must be be 4, 8, or 10. NextOffset is Offset + Size.

See also:  put-real, get-integer, get-point, get-rect, get-string, get-text

_________________________________________________
                                            get-rect 
 *316*

Input types: ABlock[@[@]] | integer;  integer

Output types: ABlock[@[@]] | integer;  integer;  Rect

Description: 
aRect is a rectangle obtained by reading eight bytes from Buffer starting at Offset bytes. NextOffset is Offset + 8.

See also:  put-rect, get-integer, get-point, get-real, get-string, get-text

_________________________________________________
                                             get-string 
 *316*

Input types: ABlock[@[@]] | integer;  integer

Output types: ABlock[@[@]] | integer;  integer;  string

Description: 
aString is a string of length N bytes, where N is the one-byte integer read from Buffer starting at Offset, and the N bytes of aString are read from Buffer starting at Offset+1. NextOffset is Offset+N+1.

See also:  put-string, get-integer, get-point, get-real, get-rect, get-text

_________________________________________________
                                            get-text 
 *316*

Input types: ABlock[@[@]] | integer;  integer;  integer

Output types: ABlock[@[@]] | integer;  integer;  string

Description: 
aString is a string of length Size bytes, read from Buffer starting at Offset bytes. Size must be greater than or equal to 0 and less than or equal to 65535. NextOffset is Offset + Size.

See also:  put-text, get-integer, get-point, get-real, get-rect, get-string

_________________________________________________
                                 lock-block 
*317*

Input types: ABlock

Description: 
Locks the handle containing Block.

See also:  unlock-block

_________________________________________________
                                lock-string 
 *317*

Input types: string

Description: 
Locks the handle containing aString.

See also:  unlock-string

_________________________________________________
                                     make-direct
 *317*

Input names: Type; Size 

Input types: string; integer 

Output types: external

Description: Block is an external structure block of size Size and type Type. Type can be any name listed under External Structures in the Info window. 

See also: make-handle, make-pointer

_________________________________________________
 
                                                       make-handle
*317*

Input names: Type; Size

 Input types: string; integer 

Output types: external@@

Description: Handle is a handle to a structure of size Size and type Type. Type can be any name listed under External Structures in the Info window. The user must use the Mac Toolbox call DisposHandle to free the memory allocated to the handle.

See also: make-direct, make-pointer

_________________________________________________

                                                        make-pointer
*318*

Input names: Type; Size 

Input types: string; integer 

Output types: external@

Description: Pointer is a pointer to a structure of size Size and type Type. Type can be any name listed under External Structures in the Info window. The user must use the Mac Toolbox call DisposPtr to free the memory allocated to the pointer.

See also: make-direct, make-handle

_________________________________________________
 
                               new-block 
 *318*

Input types: integer

Output types: ABlock

Description: 
Block is a new block of Size bytes.

See also:  block-size

_________________________________________________
                                                object-to-address
*319*

Input types: any; [ boolean ]

Output types: integer

Description: Address is the address of any Prograph object. Keep? is FALSE by default.  If TRUE, then Address is always valid and the Object is not deleted.  To recover memory in this case, address-to-object must be TRUE.

See also: address-to-object

_________________________________________________
 
                                                                      put-integer 
 *319*

Input types: ABlock[@[@]] | integer;  integer;  integer;  integer

Output types: ABlock[@[@]] | integer;  integer

Description: 
Value is converted into an integer of Size bytes, which is then put into Buffer starting at Offset. Size must be 1, 2, or 4. NextOffset is Offset + Size.

See also:  get-integer, put-point, put-real, put-rect, put-string, put-text

_________________________________________________
                                                   put-point 
 *319*

Input types: ABlock[@[@]] | integer;  integer;  Point

Output types: ABlock[@[@]] | integer;  integer  

Description: 
The four bytes of aPoint are put into Buffer at Offset. NextOffset is Offset + 4.

See also:  get-point, put-integer, put-real, put-rect, put-string, put-text

_________________________________________________
                                                                    put-real 
 *320*

Input types: ABlock[@[@]] | integer;  integer;  integer;  real

Output types: ABlock[@[@]] | integer;  integer

Description: 
Converts value into a floating point value of Size bytes, which is then put into Buffer starting at Offset. Size must be 4, 8, or 10. NextOffset is Offset + Size.

See also:  get-real, put-integer, put-point, put-rect, put-string, put-text

_________________________________________________
                                                       put-rect 
 *320*

Input types: ABlock[@[@]] | integer;  integer;  Rect

Output types: ABlock[@[@]] | integer;  integer

Description: 
Puts 8 bytes of aRect into Buffer at Offset. NextOffset is Offset + 8.
See also:  get-rect, put-integer, put-point, put-real, put-string, put-text

_________________________________________________
                                                   put-string 
 *320*

Input types: ABlock[@[@]] | integer;  integer;  string

Output types: ABlock[@[@]] | integer;  integer

Description: 
Puts N+1 bytes into Buffer starting at Offset, where N is the mimimum of 255 and the length of aString. First byte is N; the remaining N bytes are from aString. NextOffset is Offset+N+1.

See also:  get-string, put-integer, put-point, put-real, put-rect, put-text

_________________________________________________
                                                                    put-text 
 *321*

Input types: ABlock[@[@]] | integer;  integer; integer;  string

Output types: ABlock[@[@]] | integer;  integer

Description: 
Puts Size bytes from aString into Buffer starting at Offset. Size must be greater than or equal to 0 and less than or equal to 65535. NextOffset is Offset+Size.

See also:  get-text, put-integer, put-point, put-real, put-rect, put-string

_________________________________________________
                                         string-address
*321*

Input types: string

Output types: integer

Description: 
Address is the address of the first character in aString. aString should be locked whenever Address is taken or used.

See also:  block-address

_________________________________________________
                              to-handle
 *321*

Input types: integer

Output types: macintosh

Description: 
Address is the address of a master pointer to a Macintosh structure, and Mac is a handle to that structure.

See also:  from-handle, to-pointer, from-pointer

_________________________________________________
                                 to-pointer
 *322*

Input types: integer

Output types: macintosh

Description: 
Address is the address of a Macintosh structure, and Mac is a pointer to that structure.

See also:  from-pointer, to-handle, from-handle 

_________________________________________________
                                     unlock-block 
*322*

Input types: ABlock

Description: 
Unlocks the handle containing Block.

See also:  lock-block

_________________________________________________
                                     unlock-string 
*322*

Input types: string

Description: 
Unlocks the handle containing aString.

See also:  lock-string